IShUtilities Struct Reference
[Shell Utilities]

General utilities. More...

Inheritance diagram for IShUtilities:

List of all members.

Public Member Functions
virtual void MCCOMAPI	BeginProgress (const TMCString &prompt, IMCUnknown **outProgressKey, real32 inMaxValue=100.0f)=0
virtual void MCCOMAPI	EndProgress (IMCUnknown *inProgressKey)=0
virtual void MCCOMAPI	SetProgressPrompt (TMCString &inPrompt, IMCUnknown *inProgressKey=NULL)=0
virtual void MCCOMAPI	IncrementProgress (real32 inIncrement, IMCUnknown *inProgressKey=NULL)=0
virtual void MCCOMAPI	SetProgressValue (real32 inValue, IMCUnknown *inProgressKey=NULL)=0
virtual void MCCOMAPI	SetProgressValue0to1 (real32 inValue, IMCUnknown *inProgressKey=NULL)=0
virtual uint32 MCCOMAPI	TickCount ()=0
virtual uint32 MCCOMAPI	Random ()=0
virtual MCCOMErr MCCOMAPI	SetRandomSeed (uint32 newSeed)=0
virtual int32 MCCOMAPI	RandomStep (int32 before)=0
virtual uint32 MCCOMAPI	GetAPINumber ()=0
virtual MCCOMErr MCCOMAPI	Gestalt (void *data, uint32 id)=0
virtual int16 MCCOMAPI	DoAlert (EAlerts alertSeverity, const TMCString &mainMessage, const TMCString &arg0, const TMCString &arg1, const TMCString &arg2, int32 buttonsCount, const TMCString &button0, const TMCString &button1, const TMCString &button2)=0
virtual MCCOMErr MCCOMAPI	ErrorToString (MCCOMErr inErr, TMCString &outErrorString)=0
virtual void MCCOMAPI	BuildAlertMessage (MCCOMErr inErr, const TMCString &inContext, TMCString &outMessage)=0
virtual MCCOMErr MCCOMAPI	RestoreResources (void *oldResources)=0
virtual MCCOMErr MCCOMAPI	BlitUIImage (IMCGraphicContext *inGraphicContext, const TMCRect &inRect, const TMCRect &inUpdateBBox, uint32 inResourceID)=0
virtual MCCOMErr MCCOMAPI	GetUIImageInfo (uint32 inResourceID, int32 &width, int32 &height, int32 &planes)=0
virtual MCCOMErr MCCOMAPI	GetUIImageBucket (uint32 inResourceID, TMCPixelBucket *bucket)=0
virtual MCCOMErr MCCOMAPI	GetUIImage (uint32 inResourceID, TMCUIImage **outUiImage)=0
virtual MCCOMErr MCCOMAPI	CreateCompatiblePixelBucket (int32 widthParam, int32 heightParam, int32 depthParam, TMCCompatiblePixelBucket **outBucket)=0
virtual MCCOMErr MCCOMAPI	DestroyCompatiblePixelBucket (TMCCompatiblePixelBucket *outBucket)=0
virtual TMCAsciiTranslationTable *MCCOMAPI	GetAsciiTranslationTable ()=0
virtual uint32 MCCOMAPI	GetOpenDocumentsCount ()=0
virtual MCCOMErr MCCOMAPI	GetOpenDocumentByIndex (IMFDocument **document, uint32 index)=0
virtual void MCCOMAPI	GetLastOpenDocPath (TMCString &path)=0
virtual void MCCOMAPI	GetLastSaveDocPath (TMCString &path)=0
virtual void MCCOMAPI	SetLastOpenDocPath (const TMCString &path)=0
virtual void MCCOMAPI	SetLastSaveDocPath (const TMCString &path)=0
virtual int16 MCCOMAPI	StringWidth (const TMCTextStyle &inStyle, const TMCString &inString)=0
virtual void MCCOMAPI	GetTextMetrics (const TMCTextStyle &inStyle, TMCTextMetrics &outMetrics)=0
virtual IDType MCCOMAPI	GetCreator ()=0
virtual void MCCOMAPI	SetCursor (int32 cursorId)=0
virtual void MCCOMAPI	GetFontList (IMCFontList **outFontList)=0
virtual boolean MCCOMAPI	CheckForUserCancel ()=0
virtual const TMCModifiers &MCCOMAPI	GetCurrentModifiers ()=0
virtual boolean MCCOMAPI	CheckKeyDown (int16 inVirtualKey)=0
virtual boolean MCCOMAPI	WerePrefsBad ()=0
virtual int16 MCCOMAPI	Alert (EAlertButtons inAlertType, const TMCString &message, boolean &doSkip)=0
virtual void MCCOMAPI	BlitTMCUIImage (IMCGraphicContext *inGraphicContext, TMCRect &inRect, const TMCRect &inUpdateBBox, TMCUIImage *image)=0
virtual void MCCOMAPI	CreateBrowserDialog (IMFBrowserDialog **browserDialog)=0
virtual void MCCOMAPI	WriteComponentToBrowserFile (IShComponent *component, IMCFile *file)=0
virtual MCCOMErr MCCOMAPI	LoadComponentFromBrowserFile (IShComponent **component, const IDType componentFamilyID, IMCFile *file)=0
virtual MCCOMErr MCCOMAPI	LoadComponentDataFromBrowserFile (IShComponent *component, IMCFile *file)=0
virtual void MCCOMAPI	EventLoop (boolean &isDone)=0
virtual void MCCOMAPI	CreateAAGraphicContext (TMCOffscreen &inOffscreen, IMCGraphicContext **gc)=0
virtual void MCCOMAPI	QuitApplication ()=0
virtual void MCCOMAPI	GetVersion (TMCVersionNumber &outVersionNumber)=0
virtual void MCCOMAPI	GetApplicationFullName (TMCString &string)=0
virtual const TMCString *MCCOMAPI	GetErrorMessage (EMCErrorCode errorCode)=0
virtual boolean MCCOMAPI	StoreSecretInfo (const TMCString &fileName, const TMCString &infoName, void *data, uint32 dataSize)=0
virtual boolean MCCOMAPI	GetSecretInfo (const TMCString &fileName, const TMCString &infoName, void *data, uint32 dataSize)=0
virtual void MCCOMAPI	GetStandardPath (const EStandardPathID &inStandardPathID, TMCDynamicString &outPath)=0
virtual boolean MCCOMAPI	IsAnyMenuActive ()=0
virtual void MCCOMAPI	GetFileForCurrentLanguage (IMCFile *file, boolean checkIfFileExists=true, boolean addSpace=false)=0

---

Detailed Description

General utilities.

---

Member Function Documentation

virtual int16 MCCOMAPI IShUtilities::Alert (  EAlertButtons  inAlertType, const TMCString &  message, boolean &  doSkip )  [pure virtual]

Pops up an alert message with a 'skip from now on' checkbox. This function is thread safe. See also: DoAlert() Parameters: inAlertType  An EAlertButtons that tells the function how many buttons to display (1, 2, or 3). message  The message to display to the user. doSkip  Pass this false to display the alert, or true to skip. Returns a boolean corresponding to the state of the "skip from now on" checkbox. Use to avoid future alerts of this type. Returns: 0 - kAlert_Okay, 1 - kAlert_Cancel, 2 - kAlert_Other.

virtual void MCCOMAPI IShUtilities::BeginProgress (  const TMCString &  prompt, IMCUnknown **  outProgressKey, real32  inMaxValue = 100.0f )  [pure virtual]

Progress bar support function. Begins a new progress bar (you can have more than one displayed at a time). BeginProgress returns a progress key which is passed to the other progress bar functions to identify which progress bar we're modifying. See also: EndProgress, SetProgressPrompt, IncrementProgress, SetProgressValue, SetProgressValue0to1 Parameters: prompt  Title string for this bar outProgressKey  Returns a progress key to be passed to other progress bar functions inMaxValue  Max value for the progress (ie when the progress value reaches this value, the bar is filled)

virtual void MCCOMAPI IShUtilities::BlitTMCUIImage (  IMCGraphicContext *  inGraphicContext, TMCRect &  inRect, const TMCRect &  inUpdateBBox, TMCUIImage *  image )  [pure virtual]

Blits an image in a graphics context. Parameters: inGraphicContext  The graphics context in which to blit the image inRect  TMCRect coordinates of where to blit the image inUpdateBBox  Clipping bounds for where to update the screen (if this doesn't intersect inRect, this function does nothing) image  Pointer to the TMCUIImage to blit

virtual MCCOMErr MCCOMAPI IShUtilities::BlitUIImage (  IMCGraphicContext *  inGraphicContext, const TMCRect &  inRect, const TMCRect &  inUpdateBBox, uint32  inResourceID )  [pure virtual]

Blits an image stored in a UImg resource to a graphics context. Parameters: inGraphicContext  The graphics context in which to blit the image inRect  TMCRect coordinates of where to blit the image inUpdateBBox  Clipping bounds for where to update the screen (if this doesn't intersect inRect, this function does nothing) inResourceID  Resource ID of the image to blit

virtual void MCCOMAPI IShUtilities::BuildAlertMessage (  MCCOMErr  inErr, const TMCString &  inContext, TMCString &  outMessage )  [pure virtual]

Constructs an alert message for display to the user, including the context for where the alert occurred. Parameters: inErr  Error value to convert inContext  String giving alert context outMessage  Returns the output message

virtual boolean MCCOMAPI IShUtilities::CheckForUserCancel (   )  [pure virtual]

Checks the application's message queue for a user cancel request. This should be called within time-consuming operations to make sure that the operation can be cancelled if the user hits the escape key. Returns: True if the user has requested a cancel.

virtual boolean MCCOMAPI IShUtilities::CheckKeyDown (  int16  inVirtualKey  )  [pure virtual]

Checks to see if a given key is currently down. Parameters: inVirtualKey  Pass this the key code for the key you wish to check Returns: True if the key is currently pressed

virtual void MCCOMAPI IShUtilities::CreateAAGraphicContext (  TMCOffscreen &  inOffscreen, IMCGraphicContext **  gc )  [pure virtual]

Creates an antialiased graphics context Parameters: inOffscreen  The offscreen used by the graphics context gc  Returns a pointer to the graphics context

virtual void MCCOMAPI IShUtilities::CreateBrowserDialog (  IMFBrowserDialog **  browserDialog  )  [pure virtual]

Creates a browser dialog. Do not forget to call CallPrepareToDestroy before you release the dialog. Parameters: browserDialog  Returns a pointer to the new browser dialog.

virtual MCCOMErr MCCOMAPI IShUtilities::CreateCompatiblePixelBucket (  int32  widthParam, int32  heightParam, int32  depthParam, TMCCompatiblePixelBucket **  outBucket )  [pure virtual]

Creates a pixel bucket of a specified size/depth. Parameters: widthParam  Width of pixel bucket to create heightParam  Height of pixel bucket to create depthParam  Depth of pixel bucket to create outBucket  Pass this the address of a TMCCountedPtr<TMCCompatiblePixelBucket> and it will be pointed to the output bucket.

virtual MCCOMErr MCCOMAPI IShUtilities::DestroyCompatiblePixelBucket (  TMCCompatiblePixelBucket *  outBucket  )  [pure virtual]

Destroys a passed-in TMCCompatiblePixelBucket, and frees the memory used by the bucket's Offscreen. Parameters: outBucket  Pointer to bucket to be destroyed.

virtual int16 MCCOMAPI IShUtilities::DoAlert (  EAlerts  alertSeverity, const TMCString &  mainMessage, const TMCString &  arg0, const TMCString &  arg1, const TMCString &  arg2, int32  buttonsCount, const TMCString &  button0, const TMCString &  button1, const TMCString &  button2 )  [pure virtual]

Opens a basic alert box. Use this to post an alert and get a response from the user. The strings button0, button1, and button2 are optional. If they are empty strings, default values will be used. If buttonCount == 1, "OK". If buttonCount == 2, "OK Cancel", and if buttonCount == 3, "Yes No Cancel". This function is thread safe. (it can be called from a preemptive thread) Parameters: alertSeverity  Alert severity icon. See EAlerts mainMessage  Main message to display arg0  Substitution string. Any "^0" in mainMessage will be replaced by this arg1  Substitution string. Any "^1" in mainMessage will be replaced by this arg2  Substitution string. Any "^2" in mainMessage will be replaced by this buttonsCount  Number of buttons (1, 2, or 3) button0  Text for default button button1  Text for second button button2  Text for third button Returns: The value of the button hit (0, 1, or 2)

virtual void MCCOMAPI IShUtilities::EndProgress (  IMCUnknown *  inProgressKey  )  [pure virtual]

Progress bar support function. Ends a progress bar. See also: BeginProgress, SetProgressPrompt, IncrementProgress, SetProgressValue, SetProgressValue0to1 Parameters: inProgressKey  Pointer to the progress key associated with the progress bar to end. If NULL, ends the first progress bar.

virtual MCCOMErr MCCOMAPI IShUtilities::ErrorToString (  MCCOMErr  inErr, TMCString &  outErrorString )  [pure virtual]

Translates from a MCCOMErr value to a text string. Parameters: inErr  The error value to convert outErrorString  Returns the text string for that error

virtual void MCCOMAPI IShUtilities::EventLoop (  boolean &  isDone  )  [pure virtual]

Creates a local event loop. Parameters: isDone  a reference to the flag that ends the loop when it goes to true

virtual MCCOMErr MCCOMAPI IShUtilities::Gestalt (  void *  data, uint32  id )  [pure virtual]

Unlikely to need to use this. Returns state information corresponding to an ID code. Parameters: data  id

virtual uint32 MCCOMAPI IShUtilities::GetAPINumber (   )  [pure virtual]

Returns the API version.

virtual void MCCOMAPI IShUtilities::GetApplicationFullName (  TMCString &  string  )  [pure virtual]

Returns the full name of the application (ex: Carrara 4 Pro) Parameters: string  Returns the application name

virtual TMCAsciiTranslationTable* MCCOMAPI IShUtilities::GetAsciiTranslationTable (   )  [pure virtual]

Returns the global ASCII translation table. See also: TMCAsciiTranslationTable Returns: A pointer to the translation table object

virtual IDType MCCOMAPI IShUtilities::GetCreator (   )  [pure virtual]

Deprecated.

virtual const TMCModifiers& MCCOMAPI IShUtilities::GetCurrentModifiers (   )  [pure virtual]

Returns the state of the keyboard modifiers. (Things like "shift key down" and "ctrl key down".) This is generally used to enable different behaviors of mouse clicks or other keypresses. Returns: TMCModifiers& describing the various modifiers currently active

virtual const TMCString* MCCOMAPI IShUtilities::GetErrorMessage (  EMCErrorCode  errorCode  )  [pure virtual]

Internal use only. Use GetErrorMessage() instead (See MCErrorMessages.h)

virtual void MCCOMAPI IShUtilities::GetFileForCurrentLanguage (  IMCFile *  file, boolean  checkIfFileExists = true, boolean  addSpace = false )  [pure virtual]

Modify the given file to point to the correct file for the current language. Parameters: file  The file that need to be modify. checkIfFileExists  If true, the function will check if the file corresponding to the current language actually exists. addSpace  If true, adds a space between the file name and the language id

virtual void MCCOMAPI IShUtilities::GetFontList (  IMCFontList **  outFontList  )  [pure virtual]

Accessor for the Font list. Parameters: outFontList  Pass this a TMCCountedPtr<IMCFontList> and it will be pointed to the font list.

virtual void MCCOMAPI IShUtilities::GetLastOpenDocPath (  TMCString &  path  )  [pure virtual]

Gets the file path of the last opened document. This returns the full path including the filename. Parameters: path  Returns the path to the last opened document.

virtual void MCCOMAPI IShUtilities::GetLastSaveDocPath (  TMCString &  path  )  [pure virtual]

Gets the file path of the last saved document. This returns the full path including the filename. Parameters: path  Returns the path to the last saved document.

virtual MCCOMErr MCCOMAPI IShUtilities::GetOpenDocumentByIndex (  IMFDocument **  document, uint32  index )  [pure virtual]

Parameters: document  Pass this the address of a TMCCountedPtr<IMFDocument> and it will be pointed to the document at the specified index index  Index of the document to get

virtual uint32 MCCOMAPI IShUtilities::GetOpenDocumentsCount (   )  [pure virtual]

Returns: The number of open documents in the application.

virtual boolean MCCOMAPI IShUtilities::GetSecretInfo (  const TMCString &  fileName, const TMCString &  infoName, void *  data, uint32  dataSize )  [pure virtual]

Returns true if the info could be read.

virtual void MCCOMAPI IShUtilities::GetStandardPath (  const EStandardPathID &  inStandardPathID, TMCDynamicString &  outPath )  [pure virtual]

Returns the component class of a component (Very rarely used) Parameters: inStandardPathID  id of the path you need (see EStandardPathID) outPath  The (platform) full path of the folder corresponding to inStandardPathID

virtual void MCCOMAPI IShUtilities::GetTextMetrics (  const TMCTextStyle &  inStyle, TMCTextMetrics &  outMetrics )  [pure virtual]

Returns the font metrics associated with a given TMCTextStyle. Parameters: inStyle  The text style to query outMetrics  Returns the TMCTextMetrics associated with the given style

virtual MCCOMErr MCCOMAPI IShUtilities::GetUIImage (  uint32  inResourceID, TMCUIImage **  outUiImage )  [pure virtual]

Gets an image from a resource and places it in a TMCUIImage. Parameters: inResourceID  Resource ID of image to get outUiImage  Pass this the address of a TMCCountedPtr<TMCUIImage>, and it will be pointed to the output image.

virtual MCCOMErr MCCOMAPI IShUtilities::GetUIImageBucket (  uint32  inResourceID, TMCPixelBucket *  bucket )  [pure virtual]

Blits the UI Image directly into a pixel bucket. The bucket must be allocated before calling this function, so you should use GetUIImageInfo() to figure out how large the bucket needs to be, and then allocate it with CreateCompatiblePixelBucket(). Parameters: inResourceID  Resource ID of the image to get. bucket  Pointer to the pixel bucket in which to place the image.

virtual MCCOMErr MCCOMAPI IShUtilities::GetUIImageInfo (  uint32  inResourceID, int32 &  width, int32 &  height, int32 &  planes )  [pure virtual]

Gets information about the UImg resource at a given ID. Useful for sizing pixel buckets, etc. Parameters: inResourceID  ID of the resource to query width  Returns the width of the image resource height  Returns the height of the image resource planes  Returns the number of planes in the resource

virtual void MCCOMAPI IShUtilities::GetVersion (  TMCVersionNumber &  outVersionNumber  )  [pure virtual]

Returns the current version number of the application Parameters: outVersionNumber  Returns the version number

virtual void MCCOMAPI IShUtilities::IncrementProgress (  real32  inIncrement, IMCUnknown *  inProgressKey = NULL )  [pure virtual]

Progress bar support function. Increments the progress bar by inIncrement. See also: EndProgress, SetProgressPrompt, BeginProgress, SetProgressValue, SetProgressValue0to1 Parameters: inIncrement  Increment to add to the progress value. inProgressKey  Pointer to the progress key associated with the progress bar to adjust. If NULL, applies to the first progress bar.

virtual boolean MCCOMAPI IShUtilities::IsAnyMenuActive (   )  [pure virtual]

Returns true if a menu is active

virtual MCCOMErr MCCOMAPI IShUtilities::LoadComponentDataFromBrowserFile (  IShComponent *  component, IMCFile *  file )  [pure virtual]

Loads a component's data from a browser file. (The file must of course have been created from the same class as the component passed.) Parameters: component  A pointer to the component whose data you'd like to load file  A pointer to the file where the component is stored. Returns: MC_S_OK If the file contained the right type of component.

virtual MCCOMErr MCCOMAPI IShUtilities::LoadComponentFromBrowserFile (  IShComponent **  component, const IDType  componentFamilyID, IMCFile *  file )  [pure virtual]

Loads a component from a browser file See also: WriteComponentToBrowserFile Parameters: component  Returns a pointer to the component loaded componentFamilyID  ID of the component family being loaded file  A pointer to the file from which the component will be loaded Returns: MC_S_OK if the file contained the right type of component

virtual void MCCOMAPI IShUtilities::QuitApplication (   )  [pure virtual]

Posts an action to quit the application.

virtual uint32 MCCOMAPI IShUtilities::Random (   )  [pure virtual]

Returns: A pseudorandom number

virtual int32 MCCOMAPI IShUtilities::RandomStep (  int32  before  )  [pure virtual]

Given a previous pseudorandom number, generates the next one. Parameters: before  The number at which to start the random number generation process.

virtual MCCOMErr MCCOMAPI IShUtilities::RestoreResources (  void *  oldResources  )  [pure virtual]

Deprecated. See also: CWhileInCompResFile

virtual void MCCOMAPI IShUtilities::SetCursor (  int32  cursorId  )  [pure virtual]

Sets the mouse cursor. See MCCursorTypes.h Parameters: cursorId  ID of the cursor to set

virtual void MCCOMAPI IShUtilities::SetLastOpenDocPath (  const TMCString &  path  )  [pure virtual]

Sets the file path of the last opened document. Use this if you open a document, to make sure that GetLastOpenDocPath() calls correctly return the path to the document you opened. Parameters: path  The path to the last opened document

virtual void MCCOMAPI IShUtilities::SetLastSaveDocPath (  const TMCString &  path  )  [pure virtual]

Sets the file path of the last saved document. Use this if you save a document, to make sure that GetLastSaveDocPath() calls correctly return the path to the document you saved. Parameters: path  The path to the last saved document

virtual void MCCOMAPI IShUtilities::SetProgressPrompt (  TMCString &  inPrompt, IMCUnknown *  inProgressKey = NULL )  [pure virtual]

Progress bar support function. Sets the progress bar's title prompt. You can use this if you want to alter the prompt midway through the progress bar process. See also: EndProgress, BeginProgress, IncrementProgress, SetProgressValue, SetProgressValue0to1 Parameters: inPrompt  Title string for this bar inProgressKey  Pointer to the progress key associated with the progress bar to adjust. If NULL, applies to the first progress bar.

virtual void MCCOMAPI IShUtilities::SetProgressValue (  real32  inValue, IMCUnknown *  inProgressKey = NULL )  [pure virtual]

Progress bar support function. Sets the progress value to inValue. See also: EndProgress, SetProgressPrompt, IncrementProgress, BeginProgress, SetProgressValue0to1 Parameters: inValue  Value to set the progress value to inProgressKey  Pointer to the progress key associated with the progress bar to adjust. If NULL, applies to the first progress bar.

virtual void MCCOMAPI IShUtilities::SetProgressValue0to1 (  real32  inValue, IMCUnknown *  inProgressKey = NULL )  [pure virtual]

Progress bar support function. Sets the progress value to a fraction of its maximum value determined by inValue. Sets the value of the progress bar to inValue * max value. See also: EndProgress, SetProgressPrompt, IncrementProgress, SetProgressValue, BeginProgress Parameters: inValue  Value to set the progress value to inProgressKey  Pointer to the progress key associated with the progress bar to adjust. If NULL, applies to the first progress bar.

virtual MCCOMErr MCCOMAPI IShUtilities::SetRandomSeed (  uint32  newSeed  )  [pure virtual]

Sets the random number seed. Parameters: newSeed  Seed to use for random number generation.

virtual boolean MCCOMAPI IShUtilities::StoreSecretInfo (  const TMCString &  fileName, const TMCString &  infoName, void *  data, uint32  dataSize )  [pure virtual]

Returns true if the info was written.

virtual int16 MCCOMAPI IShUtilities::StringWidth (  const TMCTextStyle &  inStyle, const TMCString &  inString )  [pure virtual]

Utility to calculate the width in pixels of a string in a given text style. Useful for calculating formatting for text you need to display dynamically. Parameters: inStyle  A TMCTextStyle to use for width calculations inString  The string whose screen width we want to find Returns: The pixel width of the string

virtual uint32 MCCOMAPI IShUtilities::TickCount (   )  [pure virtual]

Returns: The system Tick Count.

virtual boolean MCCOMAPI IShUtilities::WerePrefsBad (   )  [pure virtual]

Returns: True if the application had to rebuild the prefs file on startup.

virtual void MCCOMAPI IShUtilities::WriteComponentToBrowserFile (  IShComponent *  component, IMCFile *  file )  [pure virtual]

Writes a component to a browser file. Parameters: component  A pointer to the component to write file  A pointer to the file where the component will be saved See also: LoadComponentFromBrowserFile

---

The documentation for this struct was generated from the following file:

• IShUtilities.h

---